dbt docs generateをDB接続なしで実行してみた

dbt docs generateをDB接続なしで実行するとドキュメントの内容がどう変わるのか確認してみました

モダンデータスタック(MDS)

#dbt

#dbt Core

おざわ（じ）

2024.01.28

はじめに

データアナリティクス事業本部のおざわです。今回はdbt docs generateでデータベースに接続せずにドキュメントを出力してみた結果を共有します。

今回使用したdbtのバージョンです。

❯ dbt debug
02:00:02  Running with dbt=1.7.3
02:00:02  dbt version: 1.7.3
...略...
02:00:03  adapter type: redshift
02:00:03  adapter version: 1.7.0

本記事ではRedshiftを使っていますが、他のDBでもドキュメントの生成自体は問題ないかと思います。

実行したコマンド

データベース接続できない環境でも以下のコマンドでドキュメントを生成することができます。

dbt parse
dbt docs generate --no-compile --empty-catalog

dbtのドキュメントに記載がありますが、データベースに接続しない場合は、dbtがデータベースから取得する各種メタデータが抜け落ちてしまいます。目的によっては必要な情報がドキュメントに反映されない可能性がありますので、その点はご留意ください。

This is not recommended for production environments, as it means that your documentation will be missing information gleaned from database metadata (the full set of columns in each table, and statistics about those tables)

dbt parseとオプションについて

dbt parse

最初にdbt parseについてです。target/のディレクトリが空の状態でdbt docs generateを実行すると以下のエラーで怒られますので、manifest.jsonを出力するのにdbt parseを実行します。

Unable to do partial parsing because saved manifest not found.

dbt parseはプロジェクトの内容を解析してバリデーションを行ってから、プロジェクト内のリソース（modesl, tests, macros, etc）、リソースのプロパティ、ノードの設定といった情報を含むmanifest.jsonを生成してくれます。

dbt docs generateのオプションについて

ドキュメントによるとdbt docs generateは以下の動作でプロジェクトのドキュメントを生成します。今回指定している2つのオプションは、この2番目と3番目に関係します。

index.htmlファイルをtarget/ディレクトリにコピーする
プロジェクト内のリソースをコンパイルし、コンパイル済みのコードをmanifest.jsonに含める
データベースからメタデータを取得するクエリを発行し、モデルがマテリアライズしたテーブルやビューの情報を含むcatalog.jsonを生成する

--no-compile

コンパイルはsource、model、test、analysisのソースから実行可能なSQLを出力してくれます。マクロで組まれたロジックを展開したり、ref関数からモデル同士の依存関係を解析して正しい順番でSQLを生成し、target/ディレクトリに結果を出力します。--no-compileオプションはこのコンパイルを実行しないようにするオプションです。

参考：casterdoc - What Is dbt Compile?

--empty-catalog

catalog.jsonの出力の大部分をスキップして必要最低限のjsonを生成します。catalog.jsonはプロジェクト内で生成、定義されたテーブルやビューから、統計情報やカラムのデータ型といったメタデータを取ってきて格納しておくファイルになります。

生成されるドキュメントの違い

出力したドキュメント（Models, Sources, Seeds）を並べてスクリーンショットを取りました。

左側）DB接続あり（オプションなし）
右側）DB接続なし（オプションあり）

Models

yamlファイルには、テーブルとカラムに対してNameとDescriptionのみ設定しています。何も書いていない場合にドキュメントがどうなるのか見たかったので、一部のカラムだけ設定しています。

version: 2

models:
  - name: customers
    description: My dearest customers
    columns:
      - name: customer_id
        description: Key to identify
      - name: first_order_date
        description: when a customer first ordered from us

Details

マテリアライズにTableを指定したモデルです。 Details部分にはテーブルの統計情報が出力されるため、データベース接続なしだとほぼ空の状態になります。

以下、表示されていた項目ですが、DB製品によって情報が異なるかと思います。上段のOWNER、TYPE、RELATIONと下段の全項目はデータベース接続なしだと出力されませんでした。

# 上段
TAGS: untagged
OWNER: awsuser
TYPE: table
PACKAGE: my_redshift_project
LANGUAGE: sql
RELATION: dev.public.customers
ACCESS: protected
VERSION: 
CONTRACT: Not Enforced
# 下段
APPROXIMATE ROW COUNT: 100
APPROXIMATE SIZE: 9 MB
DISK USED: 0.00%
DIST STYLE: AUTO(EVEN)
ENCODED: Y, AUTO(ENCODE)
MAX VARCHAR: 50
SORT KEY 1: AUTO(SORTKEY)
STATS OFF: 0

Columns

データベース接続なしでもname, descriptionについてはyamlファイルに書いてある内容を出力してくれました。

データ型(TYPE)については常にデータベースから取得していました。yamlファイルにdata_typeを記載してみましたが、ドキュメントには反映されずに空欄になりました。DB接続がない場合は単に空欄になり、DB接続があれば実際のデータ型が出力されます。

Code - Compiled

右側（DB接続なし）はコンパイルを実行していませんので-- compiled code not found for this modelとだけコメントが入っていました。

Lineage

リネージは違いなしでした。

Code - Source

CodeのSourceについても違いありませんでした。

Referenced By, Depends On

違いはありませんでした。

Sources

ソースについても確認してみました。今回yamlファイルにはテーブル名のみ記載してますので、DB接続なしの場合はカラムの情報が抜け落ちています。

version: 2

sources:
  - name: jaffle_shop
    tables:
      - name: customers
      - name: orders

Seeds

シードについてはモデルと同じような結果になりました。DB接続ありの場合はカラムのデータ型やテーブルの統計情報が表示されますが、DB接続なしだとyamlファイルの内容だけが出力されます。

CSVファイルはこちらを使用

version: 2

seeds:
  - name: country_codes
    description: A mapping of two letter country codes to country names
    columns:
      - name: country_code
        description: country code